Haven't had the chance to test this yet, but is changing the separator char a complete fix or is it just moving the problem around?

What happens in this case, modified from the issue raised:

# Chapter

Test

# Chapter

Test

# Chapter:2

Test

To me, it feels like the problem is the duplicate checking mechanism, not the suffix char.

Actually I've tested this on my machine and this works fine. _slugify strips non-word chars from the header ID and I wasn't able to manually create a collision using this system.

My only concern now is this will change the format of generated header IDs in a way that isn't compatible with previous library versions, so any existing markdown docs that link to [some section](#chapter-2) will no longer work.
Could break compatibility and might catch folks off guard

Yeah I don't love the lack of backwards compat. Is there a possible fix that keeps the original separator?

Keep in mind that using a different separator also makes the id make more sense when the id is "whatever-1:2" I know this is the second instance of "Whatever 1"... but if it's encoded as "whatever-1-2", I can't tell whether it's the second instance of "Whatever 1" or it's the first instance of "Whatever 1 2".

So I think it'll be difficult to make this as robust without changing the separator really.

An approach could be to make the duplicate separator configurable... Where the default initially stays - for compability, and the documenation will recommend setting it to : for new uses.

In the next major release of markdown2 you change the default to :, and document people can revert to the old behavior in the documentation.